Daml Assistant

daml is a command-line tool that does a lot of useful things related to the SDK. Using daml, you can:

  • Create new Daml projects: daml new <path to create project in>

  • Create a new project based on the create-daml-app template: daml new --template=create-daml-app <path to create project in>

  • Initialize a Daml project: daml init

  • Compile a Daml project: daml build

    This builds the Daml project according to the project config file daml.yaml (see Configuration files below).

    In particular, it will download and install the specified version of the Daml SDK (the sdk-version field in daml.yaml) if missing, and use that SDK version to resolve dependencies and compile the Daml project.

  • Launch the tools in the SDK:

    • Launch Daml Studio: daml studio
    • Launch Sandbox, Navigator and the HTTP JSON API Service: daml start You can disable the HTTP JSON API by passing --json-api-port none to daml start. To specify additional options for sandbox/navigator/the HTTP JSON API you can use --sandbox-option=opt, --navigator-option=opt and --json-api-option=opt.
    • Launch Sandbox: daml sandbox
    • Launch Navigator (Deprecated): daml navigator
    • Launch the HTTP JSON API Service: daml json-api
    • Run Daml codegen: daml codegen

  • Install new SDK versions manually: daml install <version>

    Note that you need to update your project config file <#configuration-files> to use the new version.

Command Help

To see information about any command, run it with --help.

Configuration Files

The Daml assistant and the SDK are configured using two files:

  • The global config file, one per installation, which controls some options regarding SDK installation and updates
  • The project config file, one per Daml project, which controls how the SDK builds and interacts with the project

Global Config File (daml-config.yaml)

The global config file daml-config.yaml is in the daml home directory (~/.daml on Linux and Mac, C:/Users/<user>/AppData/Roaming/daml on Windows). It controls options related to SDK version installation and upgrades.

By default it’s blank, and you usually won’t need to edit it. It recognizes the following options:

  • auto-install: whether daml automatically installs a missing SDK version when it is required (defaults to true)

  • update-check: how often daml will check for new versions of the SDK, in seconds (default to 86400, i.e. once a day)

    This setting is only used to inform you when an update is available.

    Set update-check: <number> to check for new versions every N seconds. Set update-check: never to never check for new versions.

  • artifactory-api-key: If you have a license for Daml EE, you can use this to specify the Artifactory API key displayed in your user profile. The assistant will use this to download the EE edition.

Here is an example daml-config.yaml:

auto-install: true
update-check: 86400

Project Config File (daml.yaml)

The project config file daml.yaml must be in the root of your Daml project directory. It controls how the Daml project is built and how tools like Sandbox and Navigator interact with it.

The existence of a daml.yaml file is what tells daml that this directory contains a Daml project, and lets you use project-aware commands like daml build and daml start.

daml init creates a daml.yaml in an existing folder, so daml knows it’s a project folder.

daml new creates a skeleton application in a new project folder, which includes a config file. For example, daml new my_project creates a new folder my_project with a project config file daml.yaml like this:

sdk-version: __VERSION__
name: __PROJECT_NAME__
source: daml
init-script: Main:setup
parties:
  - Alice
  - Bob
version: 1.0.0
exposed-modules:
  - Main
dependencies:
  - daml-prim
  - daml-stdlib
script-service:
  grpc-max-message-size: 134217728
  grpc-timeout: 60
  jvm-options: []
build-options: ["--ghc-option", "-Werror",
                "--ghc-option", "-v"]

Here is what each field means:

  • sdk-version: the SDK version that this project uses.

    The assistant automatically downloads and installs this version if needed (see the auto-install setting in the global config). We recommend keeping this up to date with the latest stable release of the SDK. It is possible to override the version without modifying the daml.yaml file by setting the DAML_SDK_VERSION environment variable. This is mainly useful when you are working with an external project that you want to build with a specific version.

    The assistant will warn you when it is time to update this setting (see the update-check setting in the global config to control how often it checks, or to disable this check entirely).

  • name: the name of the project. This determines the filename of the .dar file compiled by daml build.

  • source: the root folder of your Daml source code files relative to the project root.

  • init-script: the name of the Daml script to run when using daml start.

  • parties: the parties to display in the Navigator when using daml start.

  • version: the project version.

  • exposed-modules: the Daml modules that are exposed by this project, which can be imported in other projects. If this field is not specified all modules in the project are exposed.

  • dependencies: library-dependencies of this project. See Reference: Daml Packages.

  • data-dependencies: Cross-SDK dependencies of this project See Reference: Daml Packages.

  • module-prefixes: Prefixes for all modules in package See Reference: Daml Packages.

  • script-service: settings for the script service

    • grpc-max-message-size: This option controls the maximum size of gRPC messages. If unspecified this defaults to 128MB (134217728 bytes). Unless you get errors, there should be no reason to modify this.
    • grpc-timeout: This option controls the timeout used for communicating with the script service. If unspecified this defaults to 60s. Unless you get errors, there should be no reason to modify this.
    • jvm-options: A list of options passed to the JVM when starting the script service. This can be used to limit maximum heap size via the -Xmx flag.

  • build-options: a list of tokens that will be appended to some invocations of damlc (currently build and ide). Note that there is no further shell parsing applied.

  • sandbox-options: a list of options that will be passed to Sandbox in daml start.

  • navigator-options: a list of options that will be passed to Navigator in daml start.

  • json-api-options: a list of options that will be passed to the HTTP JSON API in daml start.

  • script-options: a list of options that will be passed to the Daml script runner when running the init-script as part of daml start.

  • start-navigator: Controls whether navigator is started as part of daml start. Defaults to true. If this is specified as a CLI argument, say daml start --start-navigator=true, the CLI argument takes precedence over the value in daml.yaml.